home *** CD-ROM | disk | FTP | other *** search
/ Just Call Me Internet / Just Call Me Internet.iso / archives / com / internet / sting / sting.lzh / STING / dialer / docs / rem_ctrl.txt < prev   
Text File  |  1997-05-04  |  5KB  |  100 lines
  1.  
  2. INTRODUCTION
  3.  
  4.    This file describes how other programs can remote control the STinG Dialer. 
  5.    The Dialer can be requested to either dial, or hangup, a connection. The 
  6.    requesting program (the requester) is told about success or the error that 
  7.    occured. During remote controled dialing or hangup no user interaction with 
  8.    the Dialer is required, i.e. no alerts will pop up. The requester basically 
  9.    sends a message to the Dialer that tells the Dialer about the script file 
  10.    to be used, and the maximum number of attempts that the Dailer is allowed 
  11.    to do. A success or an error message is returned, the error message contains 
  12.    a code that identifies the error. Requesting a hangup works likewise, how-
  13.    ever, no parameters are to be passed in that case.
  14.  
  15.    With STinG a local area network (LAN) can be operated. Often there will be 
  16.    a machine with a modem that is able to dial up a modem (phone) connection 
  17.    to the outside world's Internet. Murphy's law says that whenever you need 
  18.    an urgent connection to the Internet, and the modem is on hook, you'll be 
  19.    working on the machine that is farthest from the one with the modem. To work 
  20.    around Murphy's law, the Dialer's remote control facility uses UDP packets 
  21.    for the request messages, so that any computer in the LAN can launch the 
  22.    dial-up procedure.
  23.  
  24.    Since clairvoyance is not one of the usual client's abilities, it must be
  25.    told where to send the UDP packets to (i.e. the address of the machine 
  26.    running the Dialer). To that end, each STinG installation should have a 
  27.    network environment entry (i.e. a line in DEFAULT.CFG) of the general form
  28.    `DIALER=address', where `address' is either a dotted quad IP address, or
  29.    the fully qualified domain name of the machine running the Dialer.
  30.  
  31.  
  32. PROTOCOL
  33.  
  34.    Any client that wishes to remote control the Dialer first calls the STinG 
  35.    function getvstr() to find out the value of the configuration variable 
  36.    "DIALER". The resulting string is the IP address or the fully qualified 
  37.    domain name of the machine the Dialer is running on. Now a UDP message 
  38.    is sent to the specified machine, the port is defined in REM_CTRL.H.
  39.  
  40.    Each message consist of a number of bytes, specifying the meaning of the 
  41.    message, and a few additional parameters. The first two bytes form an 
  42.    integer saying if a dial-up (IP_DIAL_REQUEST) or a hang-up (IP_DIAL_HANGUP)
  43.    is requested. Nothing more is required for a hang-up request. For dial-up
  44.    requests the maximum number of attempts, and the dial script to be used,
  45.    must be specified too. The integer made of the third and the fourth byte
  46.    specifies the maximum number of dial-up attempts. Starting with the fifth
  47.    byte, the name of the dial script, terminated by a zero byte, follows.
  48.  
  49.    After sending the message the requester should anticipate a UDP message 
  50.    from the Dialer. This can be either IP_DIAL_DONE or IP_DIAL_ERROR. In case 
  51.    of IP_DIAL_ERROR the third and the fourth byte form the actual error code.
  52.    The error codes can be
  53.    
  54.         for  IP_DIAL_REQUEST  :
  55.                IP_IN_PROGRESS       The Dialer is already dialing.
  56.                IP_IS_CONNECTED      The Dialer already connected this port
  57.                                     before.
  58.                IP_SCR_NOT_FOUND     The Dialer had problems loading the 
  59.                                     script file.
  60.                IP_PORT_LOCKED       Port could not be opened, probably 
  61.                                     because another program uses it.
  62.                IP_MAX_EXCEEDED      The specified maximum number of redials 
  63.                                     have been carried out.
  64.                IP_FATAL_PROBLEM     The Dialer got a fatal error response
  65.                                     from the modem.
  66.                IP_USER_ABORT        The user aborted the dial process.
  67.                IP_OPEN_FAILED       STinG refuses to accept the connection.
  68.  
  69.         for  IP_DIAL_HANGUP  :
  70.                IP_IN_PROGRESS       During the dial process hangup requests
  71.                                     cannot be processed.
  72.                IP_OPEN_FAILED       Due to some strange reason the port
  73.                                     could not be reopened.
  74.  
  75.    Note that if IP_OPEN_FAILED is responded to IP_DIAL_REQUEST, your modem
  76.    is still off hook ! Thus the telephone company will start to charge money 
  77.    unless IP_DIAL_HANGUP is send ! For all the other error codes the modem 
  78.    is on hook afterwards. The same holds for any response to IP_DIAL_HANGUP.
  79.  
  80.  
  81. EXAMPLE
  82.  
  83.    For an example look at the Pure C sample code DIALCTRL.C. It contains 
  84.    a simple program that just implements the above discussed protocol for 
  85.    requesting a dialup.
  86.  
  87.  
  88. AUTHOR
  89.  
  90.    Any further questions or good ideas for extensions should be directed 
  91.    to :
  92.  
  93.    Peter Rottengatter
  94.    Kriegerstrasse 18
  95.    30161 Hannover
  96.    Germany
  97.  
  98.    perot@pallas.amp.uni-hannover.de
  99.  
  100.